/*--------------------------------------------------------------------------------
 * Adaptive Intelligence - Foundation Framework
 * Version 2.10
 * 
 * Data Provider Interface Definition
 *      Provides a common signature definition for classes which provide platform-
 * specific database object instances.
 *------------------------------------------------------------------------------*/

/*--------------------------------------------------------------------------------
 * System Imports
 *------------------------------------------------------------------------------*/
using System;
using System.Data;
using System.Data.Common;

namespace Adaptive.Foundation.Data
{
    /// <summary>
    /// Provides a common signature definition for classes which provide platform-
    /// specific database object instances.
    /// </summary>
    public interface IDataProvider
    {
        /*--------------------------------------------------------------------------------
         * Methods / Functions
		 *------------------------------------------------------------------------------*/
        #region Methods / Functions
        /// <summary>
        /// Creates a platform-specific connection object.
        /// </summary>
        /// <returns>
        /// An implementation that derives from <see cref="IDbConnection"/>.
        /// </returns>
        IDbConnection CreateConnection();
        /// <summary>
        /// Creates a platform-specific connection object.
        /// </summary>
        /// <param name="connectionInformation">
        /// The connection string to use when connecting to the database.
        /// </param>
        /// <returns>
        /// An implementation that derives from <see cref="IDbConnection"/>.
        /// </returns>
        IDbConnection CreateConnection(string connectionInformation);
        /// <summary>
        /// Creates a platform-specific command-execution object.
        /// </summary>
        /// <param name="connection">
        /// An <see cref="IDbConnection"/> implementation used to connect to a database.
        /// </param>
        /// <returns>
        /// An implementation that derives from <see cref="IDbCommand"/>.
        /// </returns>
        IDbCommand CreateCommand(IDbConnection connection);
        /// <summary>
        /// Creates a platform-specific command-execution object.
        /// </summary>
        /// <param name="connection">
        /// An <see cref="IDbConnection"/> implementation used to connect to a database.
        /// </param>
        /// <param name="commandText">
        /// The SQL or other command text.
        /// </param>
        /// <returns>
        /// An implementation that derives from <see cref="IDbCommand"/>.
        /// </returns>
        IDbCommand CreateCommand(string commandText, IDbConnection connection);
        /// <summary>
        /// Creates a platform-specific data adapter object.
        /// </summary>
        /// <param name="command">
        /// An <see cref="IDbCommand"/> implementation used to connect to a database.
        /// </param>
        /// <returns>
        /// An implementation that derives from <see cref="IDataAdapter"/>.
        /// </returns>
        IDataAdapter CreateAdapter(IDbCommand command);
        /// <summary>
        /// Creates a platform-specific <see cref="IDataParameter"/>-derived instance.
        /// </summary>
        /// <returns>
        /// An <see cref="IDataParameter"/>-derived instance.
        /// </returns>
        IDataParameter CreateParameterInstance();
        /// <summary>
        /// Creates a platform-specific <see cref="IDataParameter"/>-derived instance.
        /// </summary>
        /// <param name="parameterName">The name of the parameter.</param>
        /// <param name="parameterType">The data type of the parameter.</param>
        /// <param name="direction">The direction of the parameter.</param>
        /// <returns>
        /// An <see cref="IDataParameter"/>-derived instance.
        /// </returns>
        IDataParameter CreateParameterInstance(string parameterName, DbType parameterType, ParameterDirection direction);
        /// <summary>
        /// Creates a platform-specific <see cref="IDbTransaction"/>-derived instance.
        /// </summary>
        /// <param name="parentConnection">
        /// The connection instance from which the transaction originates.
        /// </param>
        /// <returns>
        /// An <see cref="IDbTransaction"/>-derived instance.
        /// </returns>
        IDbTransaction CreateTransactionInstance(IDbConnection parentConnection);
        /// <summary>
        /// Creates a platform-specific <see cref="IDbTransaction"/>-derived instance.
        /// </summary>
        /// <param name="parentConnection">
        /// The connection instance from which the transaction originates.
        /// </param>
        /// <param name="transactionName">
        /// A name to assign to the transaction instance.
        /// </param>
        /// <returns>
        /// An <see cref="IDbTransaction"/>-derived instance.
        /// </returns>
        IDbTransaction CreateTransactionInstance(IDbConnection parentConnection, string transactionName);
        /// <summary>
        /// Creates a connection string builder for the database.
        /// </summary>
        /// <returns>
        /// A <see cref="DbConnectionStringBuilder"/> instance for creating a connection string.
        /// </returns>
        DbConnectionStringBuilder CreateConnectStringBuilder();
        /// <summary>
        /// Creates a connection string builder for the database.
        /// </summary>
        /// <param name="connectString">
        /// The connect string to be parsed.
        /// </param>
        /// <returns>
        /// A <see cref="DbConnectionStringBuilder"/> instance for parsing and/or creating a connection string.
        /// </returns>
        DbConnectionStringBuilder CreateConnectStringBuilder(string connectString);
        #endregion
    }
}